ASP.NET Core 命名空間衝突問題
TLDR
- 當專案名稱包含
System或Microsoft等關鍵字時，極易引發命名空間（Namespace）衝突。 - 衝突發生時，編譯器會誤將專案內的命名空間與系統核心命名空間混淆，導致 Razor View 編譯失敗。
- 即使關閉 Global Using Directives 或降級至 .NET 5，Razor 檔案仍會因為其內部的自動產生機制而發生衝突。
- 解決方案：避免在專案名稱中使用
System或Microsoft。 - 若已發生衝突，可嘗試在
_ViewImports.cshtml或_ViewStart.cshtml中使用@namespace指令明確指定命名空間，但最根本的做法仍是更名專案。
發生情境
當專案名稱（Namespace）包含 System 或 Microsoft 等關鍵字時，編譯器在處理 Razor View 時會產生命名空間衝突。
什麼情況下會遇到這個問題：當開發者將專案名稱命名為包含 System 的字串（例如 TestNameSpace.System），並在 ASP.NET Core 專案中使用 Razor Pages 或 MVC Views 時。
此時編譯錯誤訊息會顯示類似 命名空間 'TestNameSpace.System' 中沒有類型或命名空間 'Threading' 的錯誤，這是因為編譯器將 System.Threading 誤判為 TestNameSpace.System.Threading，導致無法正確解析系統核心類別。
Global Using Directives 與隱含引用
什麼情況下會遇到這個問題：使用 .NET 6 以上版本，且專案啟用了 C# 10 的 Global Using Directives 功能。
在專案建置過程中，系統會產生一個 {專案名稱}.GlobalUsings.g.cs 檔案，其中包含預設的系統命名空間引用：
// <auto-generated/>
global using global::System;
global using global::System.Collections.Generic;
global using global::System.IO;
global using global::System.Linq;
global using global::System.Net.Http;
global using global::System.Threading;
global using global::System.Threading.Tasks;若專案名稱與這些命名空間重疊，編譯器會優先解析到專案內的命名空間，進而導致找不到系統類型的錯誤。
Razor View 的命名空間解析機制
什麼情況下會遇到這個問題：即使關閉了 Global Using 或使用舊版 .NET Framework，Razor 檔案在編譯時仍會自動產生對應的 C# 程式碼，這些程式碼會受到專案根命名空間（Root Namespace）的影響。
透過檢查 obj 目錄下產生的 .g.cs 檔案，可以發現 Razor 頁面在編譯時會自動引用特定的命名空間。若要嘗試修正，可以在 _ViewStart.cshtml 或相關設定檔中明確定義 @namespace：
@using TestNamespace.Sys.Web
@* 將 System 改為 Sys，避免與系統命名空間衝突 *@
@namespace TestNamespace.Sys.Web.Pages
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpersTIP
上述針對 .g.cs 的路徑分析主要基於 .NET 5 環境，不同版本的 ASP.NET Core 其編譯產物路徑可能有所差異。
結論與建議
- 核心建議：在建立 ASP.NET Core 專案時，應嚴格避免將專案名稱命名為
System或Microsoft，這是預防此類編譯衝突最有效的方法。 - 專案命名規範：建議使用公司名稱或專案功能作為前綴，確保命名空間的唯一性，避免與 .NET 基礎類別庫（BCL）產生名稱碰撞。
異動歷程
- 初版文件建立。